<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=us-ascii">
<title>Using --saved-pages.</title>
<!-- Originally: commprod.txt -->
<link rel="stylesheet" type="text/css" href="gs.css" title="Ghostscript Style">
</head>

<body>
<!-- [1.0 begin visible header] ============================================ -->

<!-- [1.1 begin headline] ================================================== -->

<h1>Using Saved Pages ( <code>--saved-pages=...</code> )</h1>

<!-- [1.1 end headline] ==================================================== -->

<!-- [1.2 begin table of contents] ========================================= -->

<h2>Table of contents</h2>

<ul>
<li><a href="#Keywords">Saved Pages control keywords,</a>
<li><a href="#Print_Keywords">Printing saved pages.</a>
<li><a href="#Examples">Examples.</a>
</ul>

<!-- [1.2 end table of contents] =========================================== -->

<!-- [1.3 begin hint] ====================================================== -->
<h4>
<p>
Saved pages can be printed in any order, any number of times allowing for copy
collation, manual 'duplex' printing or selecting a subset of pages.
</h4>

<!-- [1.3 end hint] ======================================================== -->

<!-- [1.0 end visible header] ============================================== -->

<hr>

<!-- [2.0 begin contents] ================================================== -->

<p>
Many raster printing devices and raster image format devices can use the command
list (clist) to save the rendering information into files or memory based structures.
Usually the clist data is rendered as soon as the page is complete, but it is`
possible to defer rendering, then output (print) after the entire file has been
converted to clist files.
<p>
Since each page is saved separately, the pages can be rendered from the clist
files in any order, any number of times.
<p>
The saved pages are accumulated in clist form as files or in memory. The default
clist storage is specified by the <code>BAND_LIST_STORAGE=</code> macro in the
make file, but if <code>BAND_LIST_STORAGE=file</code>, the clist can be forced
to be in memory using the <code>-sBandListStorage=memory</code> option.

<h2><a name="Keywords"></a>Saved Pages control keywords.</h2>
<p>
Deferring printing is controlled using the <code>--saved-page=...</code> option.
<p>
The string following the <code>--saved-page=</code> consists of keywords,
separated by white-space, commas, or other non-alphanumeric characters
such as ':', '=', ';'. If more than one keyword is given, the string should
be enclosed in double-quotes (<code>"</code>).
<p>
The '<code>-</code>' (dash), and the '<code>*</code>' asterisk), are used in
page range selections, and cannot be keyword separators.
<p>
Keywords are case independent, thus "<b><code>begin</code></b>",
"<b><code>BEGIN</code></b>", and "<b><code>Begin</code></b>" are all equivalent.
<p>
<dl>
<dt><code>begin</code>
<dd>Begins accumulating pages to a list. The clist data for each page is
saved in files or memory as discussed above, but no rendering is performed.
<p>
If the device was set for rendering into memory, is will be switched to
accumulating the page as clist files, thus <code>-dMaxBitmap</code> and
<code>-dBandingNever</code> will be ignored, as if <code>-dBandingAlways</code>
was specified.
</dl>

<dl>
<dt><code>flush</code>
<dd>Delete all clist files for all pages on the list, and reset the
list to empty, but remain in <code>saved-pages</code> mode. Subsequent
pages will be added to the list.
</dl>

 <dl>
<dt><code>end</code>
<dd>Flush any list, deleting all clist files for any accumulated pages
and stop accumulating pages, returning to rendering/output as soon as
the page is complete.
<p>
The device may render subsequent pages in memory (page buffer) as
determined by </code>-dMaxBitmap</code> and </code>-dBandingNever</code>.
</dl>

<dl>
<dt><code>copies </code><em>copy_count</em>
<dd>Set the copy count for the <code>print</code> action. The requested number
of copies will be generated for all subsequent print actions, thus
producing <b>collated</b> copies, rather than multiple copies of
each page as in normal (non-deferred) rendering and output.
<p>
A <code>--saved-pages="copies <em>#</em>"</code> option will be applied to all
print actions until a new <code>copies <em>#</em></code> is encountered
that sets the copy count to a different value. Since the
<code>copies</code> can follow the <code>print</code> command, it is
recommended that only a single <code>copies</code> be in a each
<code>--saved-pages=</code><em>...</em> string.
<p>
Note, that unless <code>-d.IgnoreNumCopies=true</code> is specified
prior to starting <code>saved-pages</code> mode, the copy count for
each page will be saved with each page, and the job will contain the
specified number of copies of each page, as well as producing the
number of collated copies of the job set by the <code>copies</code>
in a <code>--saved-pages=</code><em>...</em> string.
</dl>

<dl>
<dt><code>print </code><em>print keywords</em>
<dd>Print from the list of saved pages. The <em>print keywords</em>
follwing the <code>print</code> action keyword determine what is
printed, and in what order. The keywords are described in the next
section.
</dl>


<h3><a name="Print_Keywords"></a>Printing Saved Pages</h3>

<p>
The string following the <code>print</code> action keyword determines which pages
from the list are printed, in what order. Any sequence of keywords, page numbers
or page ranges can follow the <code>print</code> keyword. The first control keyword
(other than <code>copies</code>) ends the list of printing keywords.
<p>
As with control keywords, print keywords can be any mixture of upper or lower case,
and print keyword, page numbers and page ranges can be seperated by any non-alphanumeric
character other than '<code>-</code>' or '<code>*</code>'.
<p>
The following are all equivalent:
<blockquote><dl>
<dt><code>1 3 5 - *</code>
<dt><code>1, 3, 5-*</code>
<dt><code>1,3,5-*</code>
</dl></blockquote>

<dl>
<dt><code>copies </code><em>copy_count</em>
<dd>As mentioned above, the <code>copies</code> keyword and count can follow the <code>print</code>
keyword. See the description of the <code>copies</code> keyword in the previous section.
<p>
The copy count will be applied to the entire sequence of print keywords, so it can
appear anywhere in the sequence of page number, page ranges or print keywords.
</dl>

<dl>
<dt><code>normal</code>
<dd>Print all of the pages, from the first until the last page in the list. This
keyword is used to print collated copies in the usual page order. This is the
same as the page range: <code>"1 - *"</code>
</dl>

<dl>
<dt><code>reverse</code>
<dd>Print all of the pages, from the last backwards to the first page in the list. This
keyword is used to print collated copies in the reverse page order. This is the
same as the page range: <code>"* - 1"</code>
</dl>

<dl>
<dt><code>odd</code>
<dd>Print all odd number pages, from 1 to the last odd numbered page. This keyword,
combined with the <code>even</code> keyword and user interaction to place pages that
were printed into the input tray, can be used for manual duplexing.
</dl>

<dl>
<dt><code>even</code>
<dd>Print all even number pages, from 2 to the last even numbered page, then if the
list has an odd number of pages print a blank 'pad' page to be the back of the last odd
page. This keyword, combined with the <code>odd</code> keyword and user interaction to
place pages that were printed into the input tray, can be used for manual duplexing.
</dl>

<dl>
<dt><code>even0pad</code>
<dd>Print all even number pages, from 2 to the last even numbered page, without any
blank 'pad' page as with the <code>even</code> keyword.
</dl>

 <dl>
<dt><em>page_number</em>
<dd>A number not followed by '<code>-</code>' specifies a single page from the
list to be printed. <b> The '<code>*</code>' character represents the last page in
the list, interpreted as a number, either as a single <em>page_number</em> or as the
<em>start_page</em> or <em>end_page</em> in a page range.
</b>
</dl>

 <dl>
<dt><em>start_page</em> <code>-</code> <em>end_page</em>
<dd>A range of pages is two <em>page_number</em>s or <code>*</code> separated by a
'<code>-</code>', optionally surrounded by non-alphanumeric characters other than
'<code>-</code>' which is a special character in page range specifications. The
pages from the <em>start_page</em> to the <em>end_page</em> are printed.
<p>
If the <em>start_page</em> is after the <em>end_page</em>, then the order of the
pages is reversed, from the <em>start_page</em> back to the <em>end_page</em>.
</dl>

<h2><a name="Examples"></a>Examples.</h2>
The following examples each print 2 collated copies from the first page to the last page:

<blockquote><dl><code>
<dt>--saved-pages="print: normal, copies=2"
<dt>--saved-pages="print copies=2, normal"
<dt>--saved-pages="copies 2 print normal"
<dt>--saved-pages="print 1-* 1-*"
<dt>--saved-pages="print normal normal"
</code></dl></blockquote>

Print the last page,  followed by all pages in reverse order, then the first page
(print reverse with two copies of the last and first page):
<blockquote><dl><code>
<dt>--saved-pages="print * reverse 1"
<dt> -or-
<dt>--saved-pages="print * * - 1 1"
</code></dl></blockquote>

Using the command line arguments with a PostScript or PDF input file to print
the odd pages, prompt the operator to reload the printer with the pages that
were printed, then print the even pages:

<blockquote><dl><code>
<dt>gs -sDEVICE=pgmraw -o /dev/lp0 --saved-pages="begin" examples/annots.pdf \
<dt>--saved-pages="print odd" \
<dt>-c "(Move printed pages to the input tray, then press enter.) = flush .confirmread)" \
<dt>--saved-pages="print even"
</code></dl></blockquote>

Print two collated copies of the first file, followed by 5 copies of the second file:
<blockquote><dl><code>
<dt>gs -sDEVICE=pgmraw -o /dev/lp0 --saved-pages="begin" examples/annots.pdf \
<dt>--saved-pages="copies=2 print normal flush" \
<dt>examples/colorcir.ps \
<dt>--saved-pages="copies=5 print normal"
</code></dl></blockquote>

<!-- [2.0 end contents] ==================================================== -->

<!-- [3.0 begin visible trailer] =========================================== -->
<hr>

<p>
<small>Copyright &copy; 2013 Artifex Software, Inc.  All rights
reserved.</small>

<p>
This software is provided AS-IS with no warranty, either express or
implied.

This software is distributed under license and may not be copied,
modified or distributed except as expressly authorized under the terms
of the license contained in the file LICENSE in this distribution.

For more information about licensing, please visit
http://www.artifex.com/licensing/
or contact Artifex Software, Inc., 7 Mt. Lassen Drive - Suite A-134,
San Rafael, CA  94903, U.S.A., +1(415)492-9861.

<p>
<small>Ghostscript version 9.19, 23 March 2016

<!-- [3.0 end visible trailer] ============================================= -->

</body>
</html>
